﻿LibraryGuard
-------------------------------------------------------------------------------------

Copyright (c) 2012, Jakub 'Fiołek' Fijałkowski <http://fiolek.org>
See License.txt for full license text.

-------------------------------------------------------------------------------------

### 1. Table of Contents: ###

1. Table of Contents
2. Overview
3. Features
4. Requirements
5. Usage
6. Additional information
7. Path format
8. Future of the project
9. Contact

-------------------------------------------------------------------------------------

### 2. Overview ###

LibraryGuard is the small project that was intended to help with music library. If
somebody is pedantic about his/her music, for example path needs to match tags, clean
folder hierarchy etc., this program should help.

This isn't fully featured version, but it fits my requirements quite well and will
not be improved unless it gets attention from other people(or me ;) ).

-------------------------------------------------------------------------------------

### 3. Features ###

This application uses so-called(by me) *guards*, i.e. parts of the program that are
responsible for single action.

For version 0.3.5 there are 5 of them:

* Path guard - checks for path consistency with tags
* Playlist guard - creates one big playlist with files
* Tags guard - checks for unnecessary strings in tags
* Unwanted files guard - removes files that were created by other program(eg. hidden
  images)
* Empty directories guard - removes empty directories

*LibraryGuard* can also run in two **modes**:

* normal - doesn't ask for user's permission for any action
* interactive - user must agree that she/he wants to perform action that have
  reflection on disk(unavailable in service)

-------------------------------------------------------------------------------------

### 4. Requirements ###

This application should run on every computer that is capable of running .NET 4
Client Profile.

-------------------------------------------------------------------------------------

### 5. Usage ###

Current release can run as a normal application and as a Windows Service. The only
difference is that the service works truly in background - there is no possibility to
interact with it.

*LibraryGuard* takes one mandatory parameter(`ConfigFile`) and one optional switch
(`SaveConfig`). Config file structure is described inside sample config. SaveConfig
gives user the ability to get pure, empty config file.

After changing config file, you can just open `cmd`, go to directory with
application, type `LibraryGuard.exe /ConfigFile:"path to config.xml` and
you're done!


If you want to install *LibraryGuard* as a service, you must use `InstallUtil.exe`
that comes with .NET Framework. It is located in
`%windir%\Microsoft.NET\Framework\v4.0.30319\InstallUtil.exe` or
`%windir%\Microsoft.NET\Framework64\v4.0.30319\InstallUtil.exe`(64-bit
version).

You must specify one additional parameter(`ConfigFile`) that points to
configuration file you want to use.
It is highly recommended to have custom [NLog configuration][nlog],
because without that application won't log anything.

`InstallUtil.exe /ConfigFile="path to config.xml" LibraryGuard.exe`

[nlog]: http://nlog-project.org/wiki/Configuration_file

-------------------------------------------------------------------------------------

### 6. Additional information ###

#### Continuous mode ####

*LibraryGuard* supports *continuous mode*. When it is enabled, it watches directories
for changes and reacts at them(immediately or only on scheduled hours). This is the
recommended mode because current version doesn't support priorities of actions and,
for example, file can be moved before its tags get corrected.

#### Scheduled mode ####

Program can work in *scheduled mode*. You can specify how long it should work and
then, how long it should be in *sleep*. It is useful for people that listen to music
and change tags at the same time and don't want to have their pleasure to be
interrupted. Program can collect changes and, for example, during night perform them.

**Scheduled mode doesn't turn off continuous mode!**

#### FLib ####

As you can see, this application comes with FLib.dll that is my utility library.
Not yet available for public but if someone wants to try it - go ahead, this release
is under MIT license.

-------------------------------------------------------------------------------------

### 7. Path format ###

*Path guard* behavior is controlled by `Format` property. It is pure text with
control blocks.
Control block is a combination of concatenations of variables, string/number literals
and function calls. There are several predefined variables:

* artist
* artists
* title
* album
* year
* genre
* genres
* composer
* composers
* albumartists
* track
* totaldiscs
* comment
* extension(extension of the file)

which corresponds to ID3v2 tags(more specifically, to foobar2000 names).

There are several functions available:

* `trim(string data, string chars)` - removes all occurences of specified chars,
  equivalent of `System.String.Trim`
* `trimstart(string data, string chars)` - removes all leading of specified
  chars, equivalent of `System.String.TrimStart`
* `trimend(string data, string chars)` - removes all trailing of specified
  chars, equivalent of `System.String.TrimEnd`
* `padleft(string data, string char, int length)` - pads data with char from
  the left to have specified length
* `padright(string data, string char, int length)` - pads data with char from
  the right to have specified length
* `pad(string data, string char, int length)` - pads data with char, placing
  data in the middle, to have specified length
* `safename(string str)` - returns name that can be used in paths(removes all
  invalid charactes with one exception **/** is replaced with **-**)

Variables and functions are case insensitive. A string must be placed inside quotes,
eg. `"this is string"`.

Control block is a string inside `${` and `}`, concatenation is done using plus
sign(**+**).

There are also conditions, which looks like this: `$[(condition) code]`, where
`code` is the same thing that can be placed inside control blocks.

`Condition` is simple comparison, C-like.
Available operators: ==, !=, >, <, >=, <=.

-------------------------------------------------------------------------------------

### 8. Future of the project ###

This project works and that was the goal of my work. If I need improvements or there
are some response from the community, I will get back to development, but for now I
don't have enough motivation(and enough time, but that's not the main problem).
So if you like the project and want it to be developed, feel free to contact me.

-------------------------------------------------------------------------------------

### 9. Contact ###

You can contact with me by [e-mail][email],
[Jabber(XMPP)][xmpp] or [Gadu-Gadu][gg].
I prefer my native language(Polish), but should be able to respond in English
(but as you probably have seen, it isn't perfect).

You can also visit [my blog][blog](only in Polish).

[email]: mailto:fiolek__DELETE__@fiolek.org
[xmpp]: xmpp:fiolek@aqq.eu
[gg]: gg:7812094
[blog]: http://blog.fiolek.org